API Temporal di JavaScript: Gestione Moderna di Date e Orari per un Pubblico Globale

L'oggetto `Date` di JavaScript è stato a lungo una fonte di frustrazione per gli sviluppatori. La sua mutabilità, l'API incoerente e lo scarso supporto per i fusi orari hanno portato alla creazione di numerose librerie come Moment.js e date-fns per colmare le lacune. Ora, con l'API Temporal, JavaScript offre una soluzione moderna e integrata per gestire date e orari con maggiore chiarezza e precisione. Questo articolo fornisce una panoramica completa dell'API Temporal, concentrandosi sulle sue caratteristiche, vantaggi e utilizzo in diversi contesti internazionali.

Cos'è l'API Temporal?

L'API Temporal è un nuovo oggetto globale in JavaScript progettato per risolvere le carenze dell'oggetto `Date`. Fornisce un'API pulita e immutabile per lavorare con date, orari, fusi orari e sistemi di calendario. Fondamentalmente, mira a rappresentare i concetti di data e ora in un modo che si allinei più strettamente con l'uso e le aspettative del mondo reale, rendendo l'internazionalizzazione molto più semplice.

Caratteristiche Principali:

• Immutabilità: Gli oggetti Temporal sono immutabili, il che significa che operazioni come l'aggiunta di giorni o mesi restituiscono nuovi oggetti invece di modificare l'originale. Questo elimina una fonte comune di bug e rende il codice più facile da analizzare.
• API Chiara: Temporal fornisce un'API coerente e intuitiva per le operazioni comuni su date e orari.
• Supporto per Fusi Orari: Temporal include un robusto supporto per i fusi orari, consentendo di lavorare con date e orari in luoghi diversi senza le complessità del vecchio oggetto `Date`. Utilizza il database dei fusi orari IANA, garantendo informazioni accurate e aggiornate.
• Sistemi di Calendario: Oltre al calendario gregoriano, Temporal supporta sistemi di calendario alternativi, rispondendo alle esigenze di diverse culture e regioni.
• Precisione Migliorata: Temporal offre una precisione al nanosecondo, superando i limiti dell'oggetto `Date` basato sui millisecondi.

Oggetti Base di Temporal

L'API Temporal introduce diversi nuovi tipi di oggetti. Ecco alcuni di quelli principali:

• `Temporal.PlainDate`: Rappresenta una data (anno, mese, giorno) senza un fuso orario.
• `Temporal.PlainTime`: Rappresenta un orario (ora, minuto, secondo, millisecondo, microsecondo, nanosecondo) senza una data o un fuso orario.
• `Temporal.PlainDateTime`: Rappresenta una data e un orario senza un fuso orario.
• `Temporal.ZonedDateTime`: Rappresenta una data e un orario con un fuso orario specifico.
• `Temporal.Instant`: Rappresenta un momento specifico nel tempo, misurato in nanosecondi dall'epoca Unix (1 gennaio 1970 UTC).
• `Temporal.TimeZone`: Rappresenta un fuso orario.
• `Temporal.Duration`: Rappresenta un intervallo di tempo (es. 2 ore, 30 minuti).
• `Temporal.YearMonth`: Rappresenta un anno e un mese.
• `Temporal.MonthDay`: Rappresenta un mese e un giorno.

Lavorare con le Date

Creare un `Temporal.PlainDate`

Per creare un `Temporal.PlainDate`, puoi usare il costruttore:

            const plainDate = new Temporal.PlainDate(2024, 10, 27); // Anno, Mese (1-12), Giorno
console.log(plainDate.toString()); // Output: 2024-10-27
            

              
                Copy
              
            
          

Puoi anche usare il metodo `from`, che accetta una stringa in formato ISO 8601:

            const plainDateFromString = Temporal.PlainDate.from('2024-10-27');
console.log(plainDateFromString.toString()); // Output: 2024-10-27
            

              
                Copy
              
            
          

Ottenere i Componenti della Data

Puoi accedere ai singoli componenti della data usando proprietà come `year`, `month` e `day`:

            console.log(plainDate.year); // Output: 2024
console.log(plainDate.month); // Output: 10
console.log(plainDate.day); // Output: 27
            

              
                Copy
              
            
          

Aritmetica delle Date

Per aggiungere o sottrarre giorni, settimane, mesi o anni, usa i metodi `plus` e `minus`. Questi metodi restituiscono un nuovo oggetto `Temporal.PlainDate`:

            const nextWeek = plainDate.plus({ days: 7 });
console.log(nextWeek.toString()); // Output: 2024-11-03

const lastMonth = plainDate.minus({ months: 1 });
console.log(lastMonth.toString()); // Output: 2024-09-27
            

              
                Copy
              
            
          

Confrontare le Date

Puoi confrontare le date usando il metodo `compare`:

            const date1 = new Temporal.PlainDate(2024, 10, 27);
const date2 = new Temporal.PlainDate(2024, 11, 15);

console.log(Temporal.PlainDate.compare(date1, date2)); // Output: -1 (date1 è precedente a date2)
            

              
                Copy
              
            
          

Lavorare con gli Orari

Creare un `Temporal.PlainTime`

Per creare un `Temporal.PlainTime`, usa il costruttore:

            const plainTime = new Temporal.PlainTime(10, 30, 0); // Ora, Minuto, Secondo
console.log(plainTime.toString()); // Output: 10:30:00
            

              
                Copy
              
            
          

Oppure usa il metodo `from` con una stringa di orario ISO 8601:

            const plainTimeFromString = Temporal.PlainTime.from('10:30:00');
console.log(plainTimeFromString.toString()); // Output: 10:30:00
            

              
                Copy
              
            
          

Ottenere i Componenti dell'Orario

            console.log(plainTime.hour); // Output: 10
console.log(plainTime.minute); // Output: 30
console.log(plainTime.second); // Output: 0
            

              
                Copy
              
            
          

Aritmetica degli Orari

            const later = plainTime.plus({ minutes: 15 });
console.log(later.toString()); // Output: 10:45:00
            

              
                Copy
              
            
          

Lavorare con Data e Ora Insieme

Creare un `Temporal.PlainDateTime`

Puoi creare un `Temporal.PlainDateTime` direttamente o combinando un `Temporal.PlainDate` e un `Temporal.PlainTime`:

            const plainDateTime = new Temporal.PlainDateTime(2024, 10, 27, 10, 30, 0);
console.log(plainDateTime.toString()); // Output: 2024-10-27T10:30:00

const date = new Temporal.PlainDate(2024, 10, 27);
const time = new Temporal.PlainTime(10, 30, 0);
const combinedDateTime = date.toPlainDateTime(time);
console.log(combinedDateTime.toString()); // Output: 2024-10-27T10:30:00
            

              
                Copy
              
            
          

Fusi Orari

Gestire correttamente i fusi orari è cruciale per le applicazioni che trattano con utenti in luoghi diversi. L'API Temporal fornisce un robusto supporto ai fusi orari attraverso gli oggetti `Temporal.ZonedDateTime` e `Temporal.TimeZone`.

Creare un `Temporal.ZonedDateTime`

Per creare un `Temporal.ZonedDateTime`, hai bisogno di un `Temporal.PlainDateTime` e di un identificatore di fuso orario. Gli identificatori di fuso orario si basano sul database dei fusi orari IANA (es. `America/Los_Angeles`, `Europe/London`, `Asia/Tokyo`).

            const plainDateTime = new Temporal.PlainDateTime(2024, 10, 27, 10, 30, 0);
const timeZone = 'America/Los_Angeles';
const zonedDateTime = plainDateTime.toZonedDateTime(timeZone);
console.log(zonedDateTime.toString()); // Output: 2024-10-27T10:30:00-07:00[America/Los_Angeles] (L'offset dipenderà dalle regole dell'ora legale)

            

              
                Copy
              
            
          

In alternativa, crea un `Temporal.ZonedDateTime` da un `Instant`.

            const instant = Temporal.Instant.fromEpochSeconds(1666866600); // Timestamp di esempio
const zonedDateTimeFromInstant = instant.toZonedDateTimeISO(timeZone); // Fuso orario come 'America/Los_Angeles'
console.log(zonedDateTimeFromInstant.toString());
            

              
                Copy
              
            
          

Convertire tra Fusi Orari

Puoi convertire un `Temporal.ZonedDateTime` in un fuso orario diverso usando il metodo `withTimeZone`:

            const newTimeZone = 'Europe/London';
const zonedDateTimeInLondon = zonedDateTime.withTimeZone(newTimeZone);
console.log(zonedDateTimeInLondon.toString()); // Output: 2024-10-27T18:30:00+01:00[Europe/London]
            

              
                Copy
              
            
          

Lavorare con gli Offset dei Fusi Orari

Il metodo `getOffsetStringFor` dell'oggetto `Temporal.TimeZone` fornisce la stringa di offset per un dato `Temporal.Instant`:

            const timeZoneObject = new Temporal.TimeZone(timeZone);
const offsetString = timeZoneObject.getOffsetStringFor(zonedDateTime.toInstant());
console.log(offsetString); // Output: -07:00 (A seconda delle regole dell'ora legale)
            

              
                Copy
              
            
          

È essenziale utilizzare gli identificatori di fuso orario IANA corretti per calcoli accurati. Questi identificatori sono mantenuti e aggiornati regolarmente per riflettere i cambiamenti nell'ora legale e nei confini dei fusi orari.

Durate

L'oggetto `Temporal.Duration` rappresenta un intervallo di tempo. Può essere usato per aggiungere o sottrarre da date e orari.

Creare un `Temporal.Duration`

Puoi creare un `Temporal.Duration` usando il costruttore, specificando anni, mesi, giorni, ore, minuti, secondi, millisecondi, microsecondi e nanosecondi:

            const duration = new Temporal.Duration(1, 2, 3, 4, 5, 6, 7, 8, 9); // Anni, Mesi, Giorni, Ore, Minuti, Secondi, Millisecondi, Microsecondi, Nanosecondi
console.log(duration.toString()); // Output: P1Y2M3DT4H5M6.007008009S
            

              
                Copy
              
            
          

Oppure usando una stringa di durata ISO 8601:

            const durationFromString = Temporal.Duration.from('P1Y2M3DT4H5M6S');
console.log(durationFromString.toString()); // Output: P1Y2M3DT4H5M6S
            

              
                Copy
              
            
          

Aggiungere Durate a Date e Orari

            const plainDate = new Temporal.PlainDate(2024, 10, 27);
const duration = new Temporal.Duration(0, 0, 7); // 7 giorni
const newDate = plainDate.plus(duration);
console.log(newDate.toString()); // Output: 2024-11-03
            

              
                Copy
              
            
          

Nota che l'aggiunta di durate che coinvolgono mesi o anni alle date richiede un'attenta considerazione, poiché il numero di giorni in un mese o anno può variare.

Sistemi di Calendario

L'API Temporal supporta diversi sistemi di calendario oltre a quello gregoriano. Questo è cruciale per le applicazioni che devono gestire date in vari contesti culturali. Sebbene il supporto sia ancora in evoluzione, fornisce una base per future espansioni.

Utilizzare Calendari Alternativi

Per utilizzare un calendario specifico, puoi specificarlo durante la creazione di oggetti Temporal:

            const hebrewDate = new Temporal.PlainDate(5785, 1, 1, { calendar: 'hebrew' });
console.log(hebrewDate.toString()); // L'output specifico può variare a seconda dell'implementazione e della formattazione. Richiede un polyfill in molti ambienti al momento della stesura di questo articolo.
            

              
                Copy
              
            
          

Importante: Il supporto per i calendari non gregoriani potrebbe richiedere polyfill o un supporto specifico del browser/ambiente. Controlla la documentazione dell'API Temporal e le tabelle di compatibilità dei browser per le informazioni più recenti.

Formattazione di Date e Orari

Mentre l'API Temporal si concentra sulla manipolazione di date e orari, la formattazione è tipicamente gestita dall'oggetto `Intl.DateTimeFormat`, che fa parte dell'API di Internazionalizzazione. Gli oggetti Temporal funzionano perfettamente con `Intl.DateTimeFormat`.

Utilizzare `Intl.DateTimeFormat`

Ecco come formattare un `Temporal.PlainDate` usando `Intl.DateTimeFormat`:

            const plainDate = new Temporal.PlainDate(2024, 10, 27);
const formatter = new Intl.DateTimeFormat('en-US', { year: 'numeric', month: 'long', day: 'numeric' });
console.log(formatter.format(plainDate)); // Output: October 27, 2024

const formatterGerman = new Intl.DateTimeFormat('de-DE', { year: 'numeric', month: 'long', day: 'numeric' });
console.log(formatterGerman.format(plainDate)); // Output: 27. Oktober 2024
            

              
                Copy
              
            
          

Puoi personalizzare le opzioni di formato per soddisfare le tue esigenze. Il primo argomento di `Intl.DateTimeFormat` è la locale, che determina la lingua e le convenzioni regionali utilizzate per la formattazione. L'uso di diverse locali (es. 'en-US', 'de-DE', 'fr-FR', 'ja-JP') produce formati di output diversi.

Formattare `Temporal.ZonedDateTime`

La formattazione di `Temporal.ZonedDateTime` è simile, ma puoi anche includere informazioni sul fuso orario nell'output:

            const plainDateTime = new Temporal.PlainDateTime(2024, 10, 27, 10, 30, 0);
const timeZone = 'America/Los_Angeles';
const zonedDateTime = plainDateTime.toZonedDateTime(timeZone);

const formatter = new Intl.DateTimeFormat('en-US', { year: 'numeric', month: 'long', day: 'numeric', hour: 'numeric', minute: 'numeric', timeZoneName: 'short' });
console.log(formatter.format(zonedDateTime)); // Output: October 27, 2024, 10:30 AM PDT (L'abbreviazione del fuso orario dipende dalle regole dell'ora legale)
            

              
                Copy
              
            
          

Best Practice per l'Internazionalizzazione

Quando lavori con date e orari in un contesto globale, tieni a mente le seguenti best practice:

• Usa Identificatori di Fuso Orario IANA: Usa sempre identificatori di fuso orario IANA (es. `America/Los_Angeles`, `Europe/London`) per una gestione accurata dei fusi orari.
• Sii Consapevole dell'Ora Legale: L'ora legale (DST) può influenzare gli offset dei fusi orari. L'API Temporal gestisce automaticamente le transizioni DST.
• Usa `Intl.DateTimeFormat` per la Formattazione: Usa l'oggetto `Intl.DateTimeFormat` per formattare date e orari secondo la locale dell'utente.
• Considera i Sistemi di Calendario: Se la tua applicazione deve supportare utenti in diversi contesti culturali, considera l'uso di sistemi di calendario alternativi.
• Memorizza Date e Orari in UTC: Quando si memorizzano date e orari in un database, è buona norma memorizzarli in UTC (Tempo Coordinato Universale) per evitare problemi di fuso orario. Quindi, convertili all'ora locale per la visualizzazione. Temporal fornisce metodi per la conversione da e verso UTC.
• Testa Approfonditamente: Testa la tua applicazione con diversi fusi orari, locali e sistemi di calendario per assicurarti che funzioni correttamente per tutti gli utenti.

Confronto tra l'API Temporal e l'Oggetto Date Tradizionale

Ecco una tabella che evidenzia le principali differenze e i vantaggi dell'API Temporal rispetto all'oggetto `Date` tradizionale:

Supporto dei Browser e Polyfill

Essendo un'API relativamente nuova, il supporto dei browser per l'API Temporal è ancora in evoluzione. Controlla le ultime tabelle di compatibilità dei browser (ad esempio, su MDN Web Docs) per vedere quali browser e ambienti la supportano nativamente. Per i browser più vecchi o gli ambienti senza supporto nativo, puoi usare dei polyfill per fornire la funzionalità dell'API Temporal. Cerca "Temporal API polyfill" sul web per trovare opzioni adatte.

Conclusione

L'API Temporal di JavaScript rappresenta un significativo passo avanti nella gestione di date e orari in JavaScript. La sua immutabilità, l'API chiara, il robusto supporto ai fusi orari e le capacità dei sistemi di calendario la rendono uno strumento potente per gli sviluppatori che creano applicazioni che devono lavorare con date e orari in modo accurato e affidabile in diversi contesti internazionali. Sebbene il supporto dei browser sia ancora in evoluzione, i vantaggi dell'API Temporal la rendono degna di essere imparata e adottata per i nuovi progetti. Abbracciando l'API Temporal e seguendo le best practice di internazionalizzazione, puoi creare applicazioni che offrono un'esperienza di data e ora fluida e accurata per gli utenti di tutto il mondo.

Approfondimenti

• Documentazione Ufficiale dell'API Temporal
• MDN Web Docs su Temporal